Skip to content

docs: add mxbuild setup & mx tool skill - #43

Merged
ako merged 2 commits into
mendixlabs:mainfrom
engalar:feat/mxbuild-skill
Mar 30, 2026
Merged

docs: add mxbuild setup & mx tool skill#43
ako merged 2 commits into
mendixlabs:mainfrom
engalar:feat/mxbuild-skill

Conversation

@engalar

@engalar engalar commented Mar 27, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add mxbuild-setup.md skill to .claude/skills/mendix/ for end-user delivery via mxcli init
  • Covers mxbuild download, mx check validation, and mx create-project usage
  • Addresses common AI agent mistakes: incorrect mx create-project syntax, missing mxcli docker check wrapper

Test plan

  • Baseline test: agent without skill uses wrong mx create-project syntax (mx create-project /path)
  • With skill: agent correctly uses --app-name flag and cwd-based output
  • With skill: agent recommends ./mxcli docker check over direct mx check
  • With skill: agent uses end-user paths (./mxcli) not dev paths

🤖 Generated with Claude Code

Addresses common agent mistakes when guiding users through mxbuild
setup and mx tool usage, particularly incorrect mx create-project
syntax and missing mxcli docker check as the preferred validation
wrapper.
@ako

ako commented Mar 27, 2026

Copy link
Copy Markdown
Collaborator

Review: Overlap with docker-workflow.md + factual concern

Overlap

Most of this content already exists in .claude/skills/mendix/docker-workflow.md:

  • mxcli setup mxbuild with --version, -p, --dry-run variants (lines 78-88)
  • mx create-project usage (lines 55-66)
  • mxbuild cache locations (line 92)
  • Troubleshooting: mxbuild not found, StudioPro.conf.hbs (lines 394-399)
  • Runtime-to-mxbuild copying workaround (lines 96-105)

Factual concern

This skill says mx create-project "does NOT accept an output path argument", but docker-workflow.md already documents:

~/.mxcli/mxbuild/{version}/modeler/mx create-project --app-name MyApp --output-dir /path/to/my-app

One of these is wrong. Please verify whether --output-dir exists before merging.

What's worth keeping

  • The "Common Workflow: Modify and Validate" 3-step recipe
  • Emphasizing ./mxcli docker check over direct mx check for end-user context
  • Blank project security caveat (no demo users)

Suggestion

Either trim this skill to only the non-overlapping content, or fold the useful bits into docker-workflow.md instead of creating a second skill that covers the same ground.

@github-actions github-actions Bot mentioned this pull request Mar 29, 2026
@engalar

engalar commented Mar 30, 2026

Copy link
Copy Markdown
Contributor Author

Investigation: --output-dir exists

Verified with mx v11.6.4:

$ ~/.mxcli/mxbuild/11.6.4/modeler/mx create-project --help

Usage: mx create-project [template-mpk-file]

Options:
  --app-name                    The name of the application.
  --output-dir                  Create the project in this directory.
  --language-code               Set the language code of the project.
  --sprintr-app-id              Set the App ID of Sprintr project.
  --use-mpr-format-v1           (Default: false) Use the MPR storage format version 1

So docker-workflow.md is correct — --output-dir is a valid flag. The new skill's claim that mx create-project "does NOT accept an output path argument" is wrong.

Agree with your suggestion to fold the non-overlapping content into docker-workflow.md rather than maintaining a second skill with mostly duplicate (and partially incorrect) information.

Remove mxbuild-setup.md (content already covered by docker-workflow.md)
and fold the non-overlapping caveat about blank projects lacking demo
users into docker-workflow.md.

Fixes factual error: mxbuild-setup.md incorrectly claimed mx
create-project does not accept --output-dir (verified it does in
mx v11.6.4).
@github-actions

Copy link
Copy Markdown

AI Code Review

Critical Issues

  • None

Moderate Issues

  • None

Minor Issues

  • Documentation inconsistency: The PR description states it adds a new skill file mxbuild-setup.md, but the diff only shows an edit to docker-workflow.md. If the PR is missing the new skill file, this is incomplete. However, since only one file diff was provided, we review what's visible.

What Looks Good

  • The added caveat in docker-workflow.md is accurate: blank Mendix projects created via mx create-project indeed lack demo users, causing login failures until security is configured.
  • The reference to manage-security.md is correct and helpful for users needing to set up demo users.
  • The change is minimal, focused, and addresses a common point of confusion for newcomers.

Recommendation

Approve the visible change (the caveat addition to docker-workflow.md). However, verify that the PR also includes the promised mxbuild-setup.md skill file if the description is accurate. If the new skill file is missing, request its addition before merging. Based solely on the provided diff, the documentation improvement is sound.


Automated review via OpenRouter (Nemotron Super 120B) — workflow source

@ako
ako merged commit 1bd143a into mendixlabs:main Mar 30, 2026
2 checks passed
@github-actions github-actions Bot mentioned this pull request Mar 30, 2026
ako pushed a commit that referenced this pull request Jul 27, 2026
The nightly matrix (10.24 / 11.6 / 11.12) failed only on 10.24:
TestMxCheck_DoctypeScripts/15b-fragment-slots-examples → CE6083 "Design property
Card style is not supported by your theme" at every cardWrap container (both
engines). `Card style` is an Atlas v3 (11.x) design property; the 10.x Atlas
theme doesn't define it.

The property sat on the shared `define fragment Card`, instantiated by every page
in the file, so a --@Version gate would have to gate the whole file and lose all
10.24 coverage of the content-slot feature 15b actually demonstrates. The design
property was incidental (12-styling covers design properties, gated 11.0+), so
drop it and keep `class: 'card'` — Atlas card styling that works on every version.

Verified: 15b passes on 10.24 AND 11.6.3 (0 errors, both engines). Also swept the
doctype suite for other ungated designproperties/building-block usage — 03/12/29/31
gate theirs, 15c was already fixed (#43), and *.test.mdl files aren't run by the
doctype test. fix-issue.md records the CE6083 case + the gate-vs-remove rule.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JXnEgoc2NQP1Y2TWMCMXC4
ako pushed a commit that referenced this pull request Jul 29, 2026
Two check gaps confirmed with mx check on Mendix 11.12.1 — both pass mxcli check
but fail the build:

- MDL048 (#42): `retrieve … where [id = $Var]` → CE0161. Mendix XPath has no id
  operator reachable from a microflow expression. Regex a word-boundaried `id`
  before a comparison (a user attribute can't be named `id`). Hint points at a
  GUID marketplace action OR exposing the id as a String on a view entity via
  `cast(id as string)` and constraining on that column.
- MDL049 (#43/#44): a call argument bound to an association-object path
  (`B = $Edit/M.Edit_Budget`) → CE0117. An association path isn't a value; it must
  be retrieved first. Flags an AttributePathExpr whose final segment is
  module-qualified (an association → object); an attribute value over the same
  association (`…/Name`) is not flagged.

Tests: TestValidateMicroflow_XPathIdConstraint, _AssociationObjectArg. Repros +
symptom table.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JXnEgoc2NQP1Y2TWMCMXC4
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants